<!DOCTYPE html>
<html lang="en">
<head>
  <title>Vert.x AMQP Bridge - Vert.x</title>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta content="width=device-width, initial-scale=1.0" name="viewport">
  <meta content="Vert.x is a tool-kit for building reactive applications on the JVM." name="description">
  <link href="http://vertx.io/stylesheets/docs.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/stylesheets/font-awesome.min.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/javascripts/styles/rainbow.min.css" media="screen" rel="stylesheet">
  <!-- IE 6-8 support of HTML 5 elements -->
  <!--[if lt IE 9]>
  <script src="http://static.jboss.org/theme/js/libs/html5/pre3.6/html5.min.js"></script>
  <![endif]-->

  <link rel="apple-touch-icon" sizes="57x57" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-57x57.png">
  <link rel="apple-touch-icon" sizes="60x60" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-60x60.png">
  <link rel="apple-touch-icon" sizes="72x72" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-72x72.png">
  <link rel="apple-touch-icon" sizes="76x76" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-76x76.png">
  <link rel="apple-touch-icon" sizes="114x114" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-114x114.png">
  <link rel="apple-touch-icon" sizes="120x120" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-120x120.png">
  <link rel="apple-touch-icon" sizes="144x144" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-144x144.png">
  <link rel="apple-touch-icon" sizes="152x152" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-152x152.png">
  <link rel="apple-touch-icon" sizes="180x180" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-180x180.png">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-32x32.png" sizes="32x32">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/android-chrome-192x192.png" sizes="192x192">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-96x96.png" sizes="96x96">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-16x16.png" sizes="16x16">
  <link rel="manifest" href="http://vertx.io/assets/favicons/vertx-favicon-7/manifest.json">
  <link rel="mask-icon" href="http://vertx.io/assets/favicons/vertx-favicon-7/safari-pinned-tab.svg" color="#5bbad5">
  <meta name="msapplication-TileColor" content="#7d3194">
  <meta name="msapplication-TileImage" content="http://vertx.io/assets/favicons/vertx-favicon-7/mstile-144x144.png">
  <meta name="theme-color" content="#ffffff">

  <link href="http://fonts.googleapis.com/css?family=Ubuntu:400,500,700,400italic" rel="stylesheet" type="text/css">
  <link rel="alternate" type="application/rss+xml" title="RSS"
     href="http://vertx.io/feed.xml">
  <script>
    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
    ga('create', 'UA-30144458-1', 'auto');
    ga('create', 'UA-71153120-1', 'auto', 'tracker');
    ga('send', 'pageview');
    ga('tracker.send', 'pageview');
  </script>
</head>
<body>

<a href="http://www.reactivemanifesto.org/" id="reactive-manifesto-banner">
  <img style="border: 0; position: fixed; right: 0; top:0; z-index: 9000"
    src="http://d379ifj7s9wntv.cloudfront.net/reactivemanifesto/images/ribbons/we-are-reactive-black-right.png">
</a>

<a id="skippy" class="sr-only sr-only-focusable" href="#content"><div class="container"><span class="skiplink-text">Skip to main content</span></div></a>

<header class="navbar navbar-default navbar-static-top" id="top" role="banner">
  <div class="container">
    <div class="navbar-header">
      <button class="navbar-toggle collapsed" type="button" data-toggle="collapse" data-target="#vertx-navbar-collapse">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <a href="http://vertx.io/" class="navbar-brand"><img alt="Brand" src="http://vertx.io/assets/logo-sm.png"></a>
    </div>
    <nav class="collapse navbar-collapse" id="vertx-navbar-collapse">
      <ul class="nav navbar-nav navbar-right">
        <li><a href="http://vertx.io/download/">Download</a></li>
        <li><a href="http://vertx.io/docs/">Documentation</a></li>
        <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
        <li><a href="http://vertx.io/community/">Community</a></li>
        <li><a href="http://vertx.io/materials/">Materials</a></li>
        <li><a href="http://vertx.io/blog/">Blog</a></li>        
      </ul>
    </nav>
  </div>
</header>



  <div class="page-header" id="content">
    <div class="container">
      <div class="row">
        <div class="col-sm-12">
          <h1>Vert.x AMQP Bridge</h1>
          
        </div>
      </div>
    </div>
  </div>




<div id="content">
  <div class="container docs-content">
    <div class="row">
      <div class="col-sm-12 col-md-push-9 col-md-3 hidden-xs hidden-sm">
        <div id="sidebar" data-spy="affix">
          <ul class="sectlevel1">
<li><a href="#_using_vert_x_amqp_bridge">Using Vert.x AMQP Bridge</a></li>
<li><a href="#_getting_started">Getting Started</a>
<ul class="sectlevel2">
<li><a href="#_sending_a_message">Sending a Message</a></li>
<li><a href="#_receiving_a_message">Receiving a Message</a></li>
</ul>
</li>
<li><a href="#message_payload">Message Payload</a>
<ul class="sectlevel2">
<li><a href="#_overview">Overview</a></li>
<li><a href="#_application_properties">Application Properties</a></li>
</ul>
</li>
<li><a href="#_flow_control">Flow Control</a>
<ul class="sectlevel2">
<li><a href="#_producers">Producers</a></li>
<li><a href="#_consumers">Consumers</a></li>
</ul>
</li>
<li><a href="#_connecting_using_ssl">Connecting using SSL</a></li>
<li><a href="#_sending_and_receiving_replies">Sending and Receiving replies.</a>
<ul class="sectlevel2">
<li><a href="#_sent_messages_seeking_a_reply">Sent messages seeking a reply.</a></li>
<li><a href="#_received_messages_seeking_a_reply">Received messages seeking a reply.</a></li>
</ul>
</li>
</ul>
        </div>
      </div>
      <div class="col-sm-12 col-md-pull-3 col-md-9">
        <div class="toc hidden-md hidden-lg">
          <h2>Table of Contents</h2>
          <ul class="sectlevel1">
<li><a href="#_using_vert_x_amqp_bridge">Using Vert.x AMQP Bridge</a></li>
<li><a href="#_getting_started">Getting Started</a>
<ul class="sectlevel2">
<li><a href="#_sending_a_message">Sending a Message</a></li>
<li><a href="#_receiving_a_message">Receiving a Message</a></li>
</ul>
</li>
<li><a href="#message_payload">Message Payload</a>
<ul class="sectlevel2">
<li><a href="#_overview">Overview</a></li>
<li><a href="#_application_properties">Application Properties</a></li>
</ul>
</li>
<li><a href="#_flow_control">Flow Control</a>
<ul class="sectlevel2">
<li><a href="#_producers">Producers</a></li>
<li><a href="#_consumers">Consumers</a></li>
</ul>
</li>
<li><a href="#_connecting_using_ssl">Connecting using SSL</a></li>
<li><a href="#_sending_and_receiving_replies">Sending and Receiving replies.</a>
<ul class="sectlevel2">
<li><a href="#_sent_messages_seeking_a_reply">Sent messages seeking a reply.</a></li>
<li><a href="#_received_messages_seeking_a_reply">Received messages seeking a reply.</a></li>
</ul>
</li>
</ul>
        </div>
        <div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>This component provides AMQP 1.0 producer and consumer support via a bridging layer implementing the Vert.x event bus
MessageProducer and MessageConsumer APIs over the top of <a href="https://github.com/vert-x3/vertx-proton/">vertx-proton</a>.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
this module has the tech preview status, this means the API can change between versions.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_using_vert_x_amqp_bridge">Using Vert.x AMQP Bridge</h2>
<div class="sectionbody">
<div class="paragraph">
<p>To use Vert.x AMQP Bridge, add the following dependency to the <em>dependencies</em> section of your build descriptor:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Maven (in your <code>pom.xml</code>):</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-xml" data-lang="xml">&lt;dependency&gt;
  &lt;groupId&gt;io.vertx&lt;/groupId&gt;
  &lt;artifactId&gt;vertx-amqp-bridge&lt;/artifactId&gt;
  &lt;version&gt;3.3.3&lt;/version&gt;
&lt;/dependency&gt;</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Gradle (in your <code>build.gradle</code> file):</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-groovy" data-lang="groovy">compile io.vertx:vertx-amqp-bridge:3.3.3</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_getting_started">Getting Started</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_sending_a_message">Sending a Message</h3>
<div class="paragraph">
<p>Here is a simple example of creating a <code><a href="../../jsdoc/module-vertx-js_message_producer-MessageProducer.html">MessageProducer</a></code> and sending a message with it.
First, an <code><a href="../../jsdoc/module-vertx-amqp-bridge-js_amqp_bridge-AmqpBridge.html">AmqpBridge</a></code> is created and started to establish the underlying AMQP connection,
then when this is complete the producer is created and a message sent using it. You can optionally supply a username
and password when starting the bridge, as well as supplying <code><a href="../dataobjects.html#AmqpBridgeOptions">AmqpBridgeOptions</a></code> in order
to configure various options such as for using SSL connections.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-js" data-lang="js">var AmqpBridge = require("vertx-amqp-bridge-js/amqp_bridge");
var bridge = AmqpBridge.create(vertx);
// Start the bridge, then use the event loop thread to process things thereafter.
bridge.start("localhost", 5672, function (res, res_err) {
  // Set up a producer using the bridge, send a message with it.
  var producer = bridge.createProducer("myAmqpAddress");

  var amqpMsgPayload = {
  };
  amqpMsgPayload.body = "myStringContent";

  producer.send(amqpMsgPayload);
});</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_receiving_a_message">Receiving a Message</h3>
<div class="paragraph">
<p>Here is a simple example of creating a <code><a href="../../jsdoc/module-vertx-js_message_consumer-MessageConsumer.html">MessageConsumer</a></code> and registering a handler with it.
First, an <code><a href="../../jsdoc/module-vertx-amqp-bridge-js_amqp_bridge-AmqpBridge.html">AmqpBridge</a></code> is created and started to establish the underlying AMQP connection,
then when this is complete the consumer is created and a handler registered that prints the body of incoming AMQP
messages.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-js" data-lang="js">var AmqpBridge = require("vertx-amqp-bridge-js/amqp_bridge");
var bridge = AmqpBridge.create(vertx);
// Start the bridge, then use the event loop thread to process things thereafter.
bridge.start("localhost", 5672, function (res, res_err) {
  // Set up a consumer using the bridge, register a handler for it.
  var consumer = bridge.createConsumer("myAmqpAddress");
  consumer.handler(function (vertxMsg) {
    var amqpMsgPayload = vertxMsg.body();
    var amqpBody = amqpMsgPayload.body;

    console.log("Received a message with body: " + amqpBody);
  });
});</code></pre>
</div>
</div>
<div class="paragraph">
<p>Receipt of the AMQP message is accepted automatically as soon as the consumer&#8217;s handler returns upon delivering the
message to the application.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="message_payload">Message Payload</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_overview">Overview</h3>
<div class="paragraph">
<p>The message payload is passed as a JsonObject with elements representing various sections of the
<a href="http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#section-message-format">AMQP
message</a>.</p>
</div>
<div class="paragraph">
<p>The top-level elements supported are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>body</strong>: The content for the body section of the AMQP message.</p>
</li>
<li>
<p><strong>body_type</strong>: An optional String used to indicate whether the "body" element represents an AmqpValue (default), Data, or AmqpSequence section. The values used are "value", "data", and "sequence" respectively.</p>
</li>
<li>
<p><strong>header</strong>: An optional  JsonObject representing the elements of the message Header section. Expanded below.</p>
</li>
<li>
<p><strong>properties</strong>: An optional JsonObject representing the elements of the message Properties section. Expanded below.</p>
</li>
<li>
<p><strong>application_properties</strong>: An optional JsonObject containing any application defined properties(/headers).</p>
</li>
<li>
<p><strong>message_annotations</strong>: An optional JsonObject representing any message annotations.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The elements of the optional "header" sub-element are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>durable</strong>: optional boolean indicating whether the message is durable (default false).</p>
</li>
<li>
<p><strong>priority</strong>: optional short indicating the message priority (default 4).</p>
</li>
<li>
<p><strong>ttl</strong>: optional long indicating ttl in milliseconds (no default). See also 'properties' absolute expiry time.</p>
</li>
<li>
<p><strong>first_acquirer</strong>: boolean indicating if this is the first acquirer of the message (default false)</p>
</li>
<li>
<p><strong>delivery_count</strong>: long indicating the number of previous <em>failed</em> delivery attempts for message.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The elements of the optional "properties" sub-element are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>to</strong>: optional string with address message is being sent to (no default).</p>
</li>
<li>
<p><strong>reply_to</strong>: optional string with address for replies (no default). Set automatically when sent with reply handler.</p>
</li>
<li>
<p><strong>message_id</strong>: optional string with message id (no default). Set automatically when sending with reply handler.</p>
</li>
<li>
<p><strong>correlation_id</strong>: optional string with correlation id (no default). Set automatically when implicit reply is sent.</p>
</li>
<li>
<p><strong>subject</strong>: optional string with message subject (no default).</p>
</li>
<li>
<p><strong>group_id</strong>: optional string with message group id (no default).</p>
</li>
<li>
<p><strong>group_sequence</strong>: optional long with message group sequence (no default).</p>
</li>
<li>
<p><strong>reply_to_group_id</strong>: optional string with message reply to group id (no default).</p>
</li>
<li>
<p><strong>content_type</strong>: optional string with message content type (no default). Only for use with Data body sections.</p>
</li>
<li>
<p><strong>content_encoding</strong>: optional string with message content encoding (no default).</p>
</li>
<li>
<p><strong>creation_time</strong>: optional long with message creation time in milliseconds since the unix epoch (no default).</p>
</li>
<li>
<p><strong>absolute_expiry_time</strong>: optional long with absolute expiry time as milliseconds since the unix epoch (no default).</p>
</li>
<li>
<p><strong>user_id</strong>: optional string with the id of the user sending the message (no default).</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_application_properties">Application Properties</h3>
<div class="paragraph">
<p>To send a message with application properties, the "application_properties" element is added to the payload,
containing a JsonObject whose contents represent the application property entries, which have string keys and a
object representing a simple value such as String, Boolean, Integer, etc. For example, adding a property to a sent
message could look something like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-js" data-lang="js">var applicationProperties = {
};
applicationProperties.name = "value";

var amqpMsgPayload = {
};
amqpMsgPayload.application_properties = applicationProperties;

producer.send(amqpMsgPayload);</code></pre>
</div>
</div>
<div class="paragraph">
<p>When receiving a message with application properties, the "application_properties" element is added to the JsonObject
payload returned, containing a JsonObject whose contents represent the application property entries. For example,
retrieving an application-property from a received message might look like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-js" data-lang="js">// Check the application properties section was present before use, it may not be
var appProps = amqpMsgPayload.application_properties;
if (appProps !== null) {
  var propValue = appProps.propertyName;
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_flow_control">Flow Control</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Message transfer between peers, such as clients and servers, is governed by credit in AMQP 1.0, with receiving peers
granting sending peers a number of credits to allow them to send messages. As each message is sent a unit of credit
is used up, with the receiving peer needing to replenish the senders credit over time in order for message delivery
to progress. This allows for recipients to flow control senders by governing the amount of outstanding credit
available.</p>
</div>
<div class="sect2">
<h3 id="_producers">Producers</h3>
<div class="paragraph">
<p>While a MessageProducer will buffer outgoing messages if there are insufficient credits to send them all
immediately, and then send them once credit is granted, it is typically more desirable for the application to work
in tandem with the producer and attempt to send only what it knows can actually currently be sent.</p>
</div>
<div class="paragraph">
<p>This is possible by inspecting whether the producer write queue is full, i.e it currently has no credit to send:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-js" data-lang="js">producer.writeQueueFull();</code></pre>
</div>
</div>
<div class="paragraph">
<p>This check can be used in concert with a handler that can be registered to receive callbacks whenever the producer
receives more credit and is able to send messages immediately rather than buffer them:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-js" data-lang="js">producer.drainHandler(function (v) {
  // ...do stuff and send...
});</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_consumers">Consumers</h3>
<div class="paragraph">
<p>In the case of a MessageConsumer, the bridge automatically gives 1000 credits to the sending peer when the consumer
handler is registered, and replenishes this credit automatically as messages are delivered to the handler. It is
possible to adjust the amount of credit given initially (the value must be at least 1) by adjusting the maximum
buffered message value before registering a handler, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-js" data-lang="js">consumer.setMaxBufferedMessages(5);
consumer.handler(function (msg) {
  // ...handle received messages...
});</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_connecting_using_ssl">Connecting using SSL</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You can also optionally supply <code><a href="../dataobjects.html#AmqpBridgeOptions">AmqpBridgeOptions</a></code> when creating the bridge in order to
configure various options, the most typically used of which are around behaviour for SSL connections.</p>
</div>
<div class="paragraph">
<p>The following is an example of using configuration to create a bridge connecting to a server using SSL,
authenticating with a username and password, and supplying a PKCS12 based trust store to verify trust of the server
certificate:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-js" data-lang="js">var AmqpBridge = require("vertx-amqp-bridge-js/amqp_bridge");
var bridgeOptions = {
};
bridgeOptions.ssl = true;

var trustOptions = {
  "path" : "path/to/pkcs12.truststore",
  "password" : "password"
};
bridgeOptions.pfxTrustOptions = trustOptions;

var bridge = AmqpBridge.create(vertx, bridgeOptions);
bridge.start("localhost", 5672, "username", "password", function (res, res_err) {
  // ..do things with the bridge..
});</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following is an example of using configuration to create a bridge connecting to a server requiring SSL Client
Certificate Authentication, supplying both a PKCS12 based trust store to verify trust of the server certificate and
also a PKCS12 based key store containing an SSL key and certificate the server can use to verify the client:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-js" data-lang="js">var AmqpBridge = require("vertx-amqp-bridge-js/amqp_bridge");
var bridgeOptions = {
};
bridgeOptions.ssl = true;

var trustOptions = {
  "path" : "path/to/pkcs12.truststore",
  "password" : "password"
};
bridgeOptions.pfxTrustOptions = trustOptions;

var keyCertOptions = {
  "path" : "path/to/pkcs12.keystore",
  "password" : "password"
};
bridgeOptions.pfxKeyCertOptions = keyCertOptions;

var bridge = AmqpBridge.create(vertx, bridgeOptions);
bridge.start("localhost", 5672, function (res, res_err) {
  // ..do things with the bridge..
});</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_sending_and_receiving_replies">Sending and Receiving replies.</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Like many messaging protocols, AMQP includes support for a reply-to address to be set on each message sent so that
recipients can be told where to send any responses required. The vert.x <code><a href="../../jsdoc/module-vertx-js_message-Message.html">Message</a></code>
objects also support the concept of a reply address, though when using the Event Bus the sender doesn&#8217;t set it
explicitly, and it is instead populated implicitly if a message is sent with a reply <code>Handler</code>.
This section describes how the bridge handles sending and receiving AMQP messages with reply-to while using the
Vert.x producer, consumer, and message APIs implemented by the bridge.</p>
</div>
<div class="sect2">
<h3 id="_sent_messages_seeking_a_reply">Sent messages seeking a reply.</h3>
<div class="paragraph">
<p>There are two options when sending messages to which responses are required:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Populate the AMQP reply-to address of the outgoing message explicitly.</p>
</li>
<li>
<p>Provide a reply handler when sending to populate it implicitly.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>With the first option, you may explicitly populate the "reply_to" element of the message "properties" section, as
outlined in the <a href="#message_payload">message payload overview</a>. Here you would provide a string containing the name
of the AMQP address on the server to which recipients should direct their responses, typically a named queue to which
you have already established a consumer to receive the replies. This route may be necessary if you need to receive
multiple replies to a given sent AMQP message.</p>
</div>
<div class="paragraph">
<p>With the second option a reply <code>Handler</code> may also be given in addition to the message payload
when sending a message, to be registered such that it is invoked when a [single] response message is received for the
message being sent.</p>
</div>
<div class="paragraph">
<p>To facilitate this, upon startup the bridge internally creates a consumer from a server-named dynamic address, the
name of which it then uses as the reply-to address on any AMQP messages sent when a replyHandler was given. The
bridge also populates the <em>message-id</em> of the outgoing AMQP message, and uses this value to keep track of the reply
handler. Incoming messages on the internal 'reply consumer' have their <em>correlation-id</em> values inspected in order to
match them to the reply handler originally given, requiring that reply senders populate the <em>correlation-id</em> field
with the <em>message-id</em> of the original message.</p>
</div>
<div class="paragraph">
<p>The following shows the process for the second option:</p>
</div>
<div class="imageblock" style="text-align: center">
<div class="content">
<img src="../images/producer-reply-handler.png" alt="producer reply handler">
</div>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>The producer is used to send a message to an AMQP address, providing a reply handler.</p>
</li>
<li>
<p>The bridge send implementation populates the <em>reply-to</em> and <em>message-id</em> fields of the outgoing AMQP message,
records the handler, and sends the message to the server.</p>
</li>
<li>
<p>The receiving application (perhaps also a Vert.x AMQP bridge) consumes the message and sends
a reply to its <em>reply-to</em> address, setting its <em>correlation-id</em> field as the original messages <em>message-id</em>.</p>
</li>
<li>
<p>The server dispatches the reply message to the internal 'reply consumer' of the bridge.</p>
</li>
<li>
<p>The bridge processes the AMQP message, creating the Vert.x Message with JsonObject body, uses the <em>correlation-id</em>
value to match it with the reply handler, and then invokes the handler with the reply message.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>The following is a basic example of sending a message and providing a reply-handler to process the response:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-js" data-lang="js">var amqpMsgPayload = {
};
amqpMsgPayload.body = "myRequest";

producer.send(amqpMsgPayload, function (res, res_err) {
  var amqpReplyMessagePayload = res.body();
  // ...do something with reply message...
});</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_received_messages_seeking_a_reply">Received messages seeking a reply.</h3>
<div class="paragraph">
<p>When a message arrives, its replyAddress may be inspected. If the AMQP message had its <em>reply-to</em> field populated,
then the address given will be returned from the Vert.x message replyAddress method. If no <em>reply-to</em> value was
present on the message, the value returned will be null.</p>
</div>
<div class="paragraph">
<p>There are two options when receiving messages to which responses are required:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Populate the AMQP reply-to address of an outgoing message sent explicitly using a producer.</p>
</li>
<li>
<p>Send a reply using the Message reply method.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>With the first option, you may explicitly populate the "reply_to" element of the message "properties" section, as
outlined in the <a href="#message_payload">message payload overview</a>, and send it explicitly using a producer established
to the address using the bridge.</p>
</div>
<div class="paragraph">
<p>With the second option, a reply message may be sent by calling the reply method on the Vert.x message
object. The reply method implementation ensures that the outgoing message <em>correlation-id</em> is populated appropriately
using the <em>message-id</em> of the original message, such that the response can be matched in the case the original
message was sent from a Vert.x AMQP bridge producer with a reply handler provided.</p>
</div>
<div class="paragraph">
<p>The following outlines the process for both routes, of receiving a message sent by an application (not shown), and
sending a reply:</p>
</div>
<div class="imageblock" style="text-align: center">
<div class="content">
<img src="../images/consumer-reply.png" alt="consumer reply">
</div>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>The server sends an AMQP message to the consumer, with a reply-to value set to another address.</p>
</li>
<li>
<p>The bridge processes the AMQP message, creating the Vert.x Message with JsonObject body. The Message replyAddress
is set to the reply-to value from the AMQP message.</p>
</li>
<li>
<p>The Message is passed to the consumer Handler, which processes it, inspecting the replyAddress and preparing to
send a response.</p>
</li>
<li>
<p>The handler chooses to either send a reply using an explicit producer, or call the reply method on the message
object.</p>
</li>
<li>
<p>The reply message arrives at the response address on the server, ready to be sent to a reply consumer for the
original sending application .</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>The following is a basic example of sending a reply using the message reply method:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-js" data-lang="js">consumer.handler(function (msg) {
  // ...do something with received message...then reply...
  var replyAddress = msg.replyAddress();
  if (replyAddress !== null) {
    var amqpReplyMessagePayload = {
    };
    amqpReplyMessagePayload.body = "myResponse";

    msg.reply(amqpReplyMessagePayload);
  }
});</code></pre>
</div>
</div>
</div>
</div>
</div>

        

        
          <div id="footer">
            <div id="footer-text">
              
                Last updated 2016-09-12 08:38:04 CEST
              
              
            </div>
          </div>
        
      </div>
    </div>
  </div>
</div>

<footer>
  <div class="container">
    <div class="row">
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Vert.x</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/">Home</a></li>
          <li><a href="http://vertx.io/download/">Download</a></li>
          <li><a href="http://vertx.io/docs/">Documentation</a></li>
          <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
          <li><a href="http://vertx.io/blog/">Blog</a></li>
          <li><a href="http://vertx.io/vertx2/" class="vertx-2-link">Vert.x 2</a></li>
        </ul>
      </div>
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Community</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/community/">Help &amp; Contributors</a></li>
          <li><a href="http://vertx.io/materials/">Learning materials</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx">User Group</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx-dev">Developer Group</a></li>
        </ul>
      </div>

      <div class="col-xs-12 col-sm-6 col-lg-offset-2 col-md-6 copyright">
        <p>Vert.x is open source and dual licensed under the <a href="https://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License 1.0</a> and <a href="https://www.apache.org/licenses/LICENSE-2.0.html">Apache License 2.0</a>.</p>
        <p>This website is licensed under the <a href="http://creativecommons.org/licenses/by-sa/3.0/">CC BY-SA 3.0 License</a>.<br>
        Design by <a href="http://www.michel-kraemer.com">Michel Kr&auml;mer</a>. <a href="http://www.entypo.com">Entypo pictograms</a> by Daniel Bruce.</p>
        <div class="row">
          <div class="col-xs-12 col-lg-offset-1 col-md-5">
            <a href="http://eclipse.org">
            <img class="logo eclipse-logo" src="http://vertx.io/assets/eclipse_logo_grey_small.png" width="204" height="48">
            </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-0 col-md-5">
            <a href="http://cloudbees.com">
            <img class="logo cloudbees-logo" src="http://vertx.io/assets/Button-Built-on-CB-1-grey.png" width="180" height="48">
           </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-1 col-md-5 jprofiler">
            <a href="http://www.ej-technologies.com/products/jprofiler/overview.html"
            style="text-decoration:none">
            <img class="logo jprofiler-logo" src="http://vertx.io/assets/jprofiler-logo.png" width="48" height="48"><span class="jprofiler-logo">&nbsp; JPROFILER</span>
            </a>
          </div>
        </div>
      </div>
    </div>
  </div>
</footer>

<script src="http://static.jboss.org/theme/js/libs/jquery/jquery-1.9.1.min.js"></script>
<script src="http://vertx.io/javascripts/bootstrap.min.js"></script>
<script src="http://vertx.io/javascripts/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>



<script src="http://vertx.io/javascripts/sidebar.js"></script>


</body>
</html>
